This document gives you high-level best practices for working with QDM models. Use it to choose the right modeling approach, store your models correctly, and work with Mart content safely and consistently.
Create a Model from Scratch
Create a new model from the beginning. Before you start, define your modeling intent and how you plan to use the model. This helps you choose the right model type and reduces rework later.
Choose the right model type
Select the model type that best matches your goal. If you're not sure, start with a conceptual or logical model and refine it as your requirements become clearer.
| Model Type | Use it to | Best for |
|---|---|---|
| Conceptual | Communicate at a high level and explore the domain early | Business alignment; defining scope and core entities without implementation details |
| Logical | Define entities, attributes, and relationships in a technology-agnostic way | Capturing structure, keys, and relationships; normalization; resolving ambiguity early |
| Logical/physical | Preserve logical intent while you add implementation detail | Bridging design and implementation; reducing handoff gaps |
| Physical | Design for implementation, including database-specific details | DDL forward engineering; validating datatypes, indexing, and constraints |
Save the model in the Mart Repository
After you create the model, save it in the Mart Repository. This is the authoritative location for managed models.
-
Save the model early and save it often so that you always know which model is the source of truth.
-
If you don't save the model to the Mart Repository, it stays in the temporary repository, where you have 30 days to recover it.
| Do | Don't |
|---|---|
| Define your modeling intent before you begin. | Don't start modeling before you define the purpose. |
| Choose the correct model type for your goal. | Don't go straight to a physical model unless implementation is your goal. |
| Save the model in the Mart Repository early and often. | Don't rely on the temporary repository for long-term storage. |
| Add documentation as you work. | Don't leave key assumptions undocumented. |
Open a model from Mart by using catalogs
Use catalogs to browse the Mart hierarchy and open the model, version, or template that you need. Catalog Management gives you a hierarchical view of the Mart, so that you can browse, manage, and compare catalogs. It includes capabilities that were previously available in Library Manager and Session Manager.
To open catalogs, go to Mart Catalog > Catalogs. The Catalogs page opens.
Best practices
Use libraries to organize models. Libraries contain models and versions in a tree structure. Use them to group related models by domain, team, or application, or to separate development and production implementations.
Understand how items are sorted. Items in the tree are sorted in this order: libraries, models, templates, then versions. Within libraries, models and versions are sorted alphabetically, and versions from newest to oldest. Named versions appear first, followed by delta versions.
Use icons to verify what you're opening. The left pane uses icons to show each item's type and state.
| Icon represents | Meaning |
|---|---|
| Mart root | Top of the Mart hierarchy |
| Catalog or folder | A container for organizing items |
| Mart model | A model stored in Mart |
| Model harvested to erwin ER360 | Model published to ER360 |
| Harvested model with newer, unharvested updates | Mart has changes not yet in ER360 |
| erwin DM project saved to Mart | A DM project artifact |
| Model marked as a template | A reusable template |
If you see a harvested indicator with newer, unharvested updates, confirm whether to open the latest Mart updates or use the harvested state.
Use Catalog Search to find models quickly.
| Search option | Scope | When to use |
|---|---|---|
| Loaded Catalogs | Only catalogs already loaded from Mart | First choice—faster |
| All Catalogs | All available catalogs | Only when you need broader, more complete results |
Review the Details pane before you open or edit. The right pane shows details for the selected entry, including whether a model is locked. If a model is locked, coordinate with the lock owner before you make changes.
Use the context menu carefully. Right-click a catalog entry to cut, copy, paste, delete, mark a delta version as a named version, hide or show versions, and create, search, or move entries. Be careful with destructive actions such as delete and hide—confirm that you're working on the correct library, model, or version.
| Do | Don't |
|---|---|
| Navigate through libraries to reduce duplication. | Don't rely on the model name alone to identify an artifact. |
| Use icon cues to confirm the item type. | Don't delete libraries or models without confirmation. |
| Prefer named versions for stable baselines. | Don't hide versions without documenting why. |
| Use Loaded Catalogs first, and check lock status before you edit. | Don't ignore harvested status if downstream users rely on ER360. |
Derive a new model
Derive a new model to create a new model from an existing one while you preserve the source model. Choose the derivation path that matches your goal, such as refining detail, preparing for implementation, or standardizing.
Supported derivation scenarios
| From | To | Use it to |
|---|---|---|
| Conceptual | Conceptual | Create a baseline copy for experimentation or parallel design |
| Conceptual | Logical | Add attributes and stronger structure while staying platform-agnostic |
| Conceptual | Logical/physical | Bridge logical clarity and physical detail |
| Logical | Logical | Create a new baseline for isolated design changes |
| Logical | Physical | Prepare the model for implementation |
| Physical | Logical | Abstract implementation details for redesign or standardization |
Best practices
Define the purpose first. Before you derive a model, define what it should accomplish, who will use it, and what completion looks like.
Preserve lineage. Treat the derived model as a separate artifact with its own lifecycle. Keep the source model unchanged for traceability, and use clear names to identify level and intent—for example:
-
Payments - Conceptual (Baseline)
-
Payments - Logical (Derived from Baseline)
-
Payments - Physical (Derived from Logical v1)
Validate immediately after derivation. Verify that entities or tables and relationships are complete, keys and cardinality are correct, and no critical content is missing or unexpectedly changed.
Add the appropriate level of detail. In a logical model, focus on business definitions, normalization, and naming consistency. In a physical model, focus on datatypes, constraints, indexes, and platform rules. When you move from physical to logical, preserve meaning while you remove implementation-specific detail.
Save and govern the derived model in Mart. Save it in the appropriate library. If your team uses versioning, create a named version at key milestones, such as before major edits or before publishing.
| Do | Don't |
|---|---|
| Derive from the correct baseline version. | Don't overwrite the source model when you need a new level or variant. |
| Match the derivation type to your goal. | Don't treat derivation as the final step. |
| Validate the derived model immediately. | Don't lose lineage through unclear names or missing descriptions. |
| Save the model to Mart promptly. | Don't mix abstraction levels without intent. |
Reverse engineer database models
Use reverse engineering to create or update a model from an existing database or implementation.
Best practices
Start with the right source and scope. Confirm the correct environment and connection details, the correct schema or database scope, and whether the model should represent the current state or a specific snapshot. Avoid reverse engineering from production unless it's required—use a controlled environment whenever possible.
Reverse engineer only what you need. Include only the schemas, tables, and objects relevant to your model's purpose. Exclude unused schemas, staging objects, and temporary tables when possible. A smaller, focused model is easier to validate and maintain.
Decide whether you're creating or updating. For a first-time capture, reverse engineer into a new model. If a model already exists, reverse engineer to update or synchronize it so that you can compare changes.
Validate after import.
| Verify | Expected result |
|---|---|
| Primary keys | Captured correctly |
| Foreign keys and relationships | Captured correctly |
| Datatypes and nullability | Match your expectations |
| Naming | Consistent, or exceptions documented |
If relationships are missing, they might not exist as database constraints even if they exist logically. Document these gaps in the model.
Add documentation and business meaning. Reverse engineering captures structure, but not business intent. Add entity or table descriptions, column definitions, ownership and usage notes, and criticality and source system information. Treat reverse engineering as the starting point, then complete the model with business context.
Save into Mart and version the result. Save the model under the correct library, and create a named version to preserve the as-is baseline at the time of extraction.
| Do | Don't |
|---|---|
| Confirm the environment and schema first. | Don't reverse engineer everything by default. |
| Scope the extraction to your model's purpose. | Don't assume that missing relationships mean none exist. |
| Validate keys and relationships immediately. | Don't treat extracted structure as complete documentation. |
| Create a named version and save to Mart. | Don't overwrite a curated model without versioning. |
Use the in-app chatbot assistant
Use the in-app chatbot assistant to request model updates, such as adding columns, updating business terms, or removing model objects.
Best practices
Provide specific context. When applicable, include the object name, attribute name, datatype, nullability, and naming requirements. The assistant works best when you're clear about what to change and where.
Make changes in small batches. Request one logical change at a time, or group related changes by table. Smaller batches reduce errors and make review easier.
Request documentation updates with structural changes, including column descriptions, entity descriptions, business term definitions, and notes that explain the purpose of the change.
Review changes before you save to Mart. Verify that the change was applied to the correct object, naming conventions are followed, datatypes and constraints are correct, and relationships and keys weren't affected unexpectedly.
Save and version after AI-driven edits. After you review the changes, save the model to the Mart Repository. For significant changes, create a named version before or after the update.
Recommended prompt patterns
| Task | Prompt pattern |
|---|---|
| Add a column | Add a new column <column_name> to <table/entity> with datatype <type>, nullable <yes/no>, and description <definition>. |
| Update a business term | Update the business term for <term> to: <new definition>. Apply it to <entity.column>. |
| Remove a column | Remove column <column_name> from <table/entity>. If it's referenced elsewhere, list the impacted objects before you apply the change. |
| Do | Don't |
|---|---|
| Specify exact object names and the target model level. | Don't use vague requests. |
| Request documentation updates with structural changes. | Don't assume that the assistant knows your naming standards. |
| Keep changes small and easy to verify. | Don't accept changes without review. |
| Save and version the model after review. | Don't remove objects without checking the impact. |
Use Quick Editor to change metaobjects
Use Quick Editor to add tables and columns and to update their properties in a focused editing interface.
Best practices
Use Quick Editor for fast, focused edits, such as adding a table, adding a column to an existing table, or updating table or column properties without opening multiple dialog boxes.
Select the correct item in the Model Tree. Quick Editor behaves based on the item you select.
| Select this | Quick Editor opens |
|---|---|
| A table or entity | The table property editor |
| A column or attribute | The column property editor |
| Another item | The appropriate editor for that item |
Add objects consistently. Follow naming conventions, add a description or definition when available, and specify datatypes, nullability, and default values where applicable. If you add multiple columns, add key and audit fields early so that patterns stay consistent across tables.
Make changes in small, reviewable steps. Change one object at a time, and verify the result immediately in the model view or properties.
Save to Mart after a complete set of edits so that the changes are captured as the source of truth.
| Do | Don't |
|---|---|
| Use the Model Tree to select the object before you edit. | Don't edit before you confirm the selected object. |
| Use Quick Editor for fast table and column changes. | Don't add columns without defining their purpose. |
| Keep naming consistent, and add descriptions as you work. | Don't postpone saving after several edits. |
| Save to Mart after a meaningful set of changes. | Don't rely on Quick Editor alone for validation. |